Document how to submit a revision via REST Change-Id: I8837ca63dfcd4590af4d11021fa1da735127fffb Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt index 041ad34..f6b775d 100644 --- a/Documentation/rest-api-changes.txt +++ b/Documentation/rest-api-changes.txt
@@ -1139,6 +1139,53 @@ } ---- +[[submit-revision]] +POST /changes/\{change-id\}/revisions/\{revision-id\}/submit (Submit Revision) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Submits a revision. + +The request body only needs to include a link:#submit-input[ +SubmitInput] entity if the request should wait for the merge to +complete. + +.Request +---- + POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/submit HTTP/1.0 + Content-Type: application/json;charset=UTF-8 + + { + "wait_for_merge": true + } +---- + +As response a link:#submit-info[SubmitInfo] entity is returned that +describes the status of the submitted change. + +.Response +---- + HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json;charset=UTF-8 + + )]}' + { + "status": "MERGED" + } +---- + +If the revision cannot be submitted, e.g. because the submit rule +doesn't allow submitting the revision or the revision is not the +current revision, the response is "`409 Conflict`" and the error +message is contained in the response body. + +.Response +---- + HTTP/1.1 409 Conflict + Content-Type: text/plain;charset=UTF-8 + + "revision 674ac754f91e64a0efb8087e59a176484bd534d1 is not current revision" +---- + [[ids]] IDs @@ -1591,6 +1638,23 @@ link:#file-info[FileInfo] entities. |=========================== +[[submit-info]] +SubmitInfo +~~~~~~~~~~ +The `SubmitInfo` entity contains information about the change status +after submitting. + +[options="header",width="50%",cols="1,6"] +|========================== +|Field Name |Description +|`status` | +The status of the change after submitting, can be `MERGED` or +`SUBMITTED`. + +If `wait_for_merge` in the link:#submit-input[SubmitInput] was set to +`false` the returned status is `SUBMITTED` and the caller can't know +whether the change could be merged successfully. +|========================== + [[submit-input]] SubmitInput ~~~~~~~~~~~ 